
/*
 * Copyright 2002-2021 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2021原作者。
 *
 *根据Apache许可证2.0版（“许可证”）获得许可；
 *除非符合许可证，否则不得使用此文件。
 *您可以在以下地址获取许可证副本：
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证分发的内容是按“原样”分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限和
 *许可证下的限制。
 */

package org.springframework.beans.factory.config;

import org.springframework.beans.BeansException;
import org.springframework.beans.PropertyValues;
import org.springframework.lang.Nullable;

/**
 * Subinterface of {@link BeanPostProcessor} that adds a before-instantiation callback,
 * and a callback after instantiation but before explicit properties are set or
 * autowiring occurs.
 *
 * <p>Typically used to suppress default instantiation for specific target beans,
 * for example to create proxies with special TargetSources (pooling targets,
 * lazily initializing targets, etc), or to implement additional injection strategies
 * such as field injection.
 *
 * <p><b>NOTE:</b> This interface is a special purpose interface, mainly for
 * internal use within the framework. It is recommended to implement the plain
 * {@link BeanPostProcessor} interface as far as possible.
 *
 * @author Juergen Hoeller
 * @author Rod Johnson
 * @since 1.2
 * @see org.springframework.aop.framework.autoproxy.AbstractAutoProxyCreator#setCustomTargetSourceCreators
 * @see org.springframework.aop.framework.autoproxy.target.LazyInitTargetSourceCreator
 */
/**
 *｛@link BeanPostProcessor｝的子接口，
 *和在实例化之后但在设置显式财产之前的回调
 *发生自动布线。
 *
 *＜p＞通常用于抑制特定目标bean的默认实例化，
 *例如创建具有特殊TargetSource（池化目标，
 *延迟初始化目标等），或实施其他注入策略
 *例如场注入。
 *
 *<p><b>注意：</b>此接口是一个专用接口，主要用于
 *框架内的内部使用。建议实施平原
 *｛@link BeanPostProcessor｝接口。
 *
 *@作者Juergen Hoeller
 *@作者Rod Johnson
 *@自1.2
 *@参见org.springframework.aop.framework.autoproxy.AbstractAutoProxyCreator#setCustomTargetSourceCreators
 *@参见org.springframework.aop.framework.autoproxy.target.LazyInitTargetSourceCreator
 */
public interface InstantiationAwareBeanPostProcessor extends BeanPostProcessor {

	/**
	 * Apply this BeanPostProcessor <i>before the target bean gets instantiated</i>.
	 * The returned bean object may be a proxy to use instead of the target bean,
	 * effectively suppressing default instantiation of the target bean.
	 * <p>If a non-null object is returned by this method, the bean creation process
	 * will be short-circuited. The only further processing applied is the
	 * {@link #postProcessAfterInitialization} callback from the configured
	 * {@link BeanPostProcessor BeanPostProcessors}.
	 * <p>This callback will be applied to bean definitions with their bean class,
	 * as well as to factory-method definitions in which case the returned bean type
	 * will be passed in here.
	 * <p>Post-processors may implement the extended
	 * {@link SmartInstantiationAwareBeanPostProcessor} interface in order
	 * to predict the type of the bean object that they are going to return here.
	 * <p>The default implementation returns {@code null}.
	 * @param beanClass the class of the bean to be instantiated
	 * @param beanName the name of the bean
	 * @return the bean object to expose instead of a default instance of the target bean,
	 * or {@code null} to proceed with default instantiation
	 * @throws org.springframework.beans.BeansException in case of errors
	 * @see #postProcessAfterInstantiation
	 * @see org.springframework.beans.factory.support.AbstractBeanDefinition#getBeanClass()
	 * @see org.springframework.beans.factory.support.AbstractBeanDefinition#getFactoryMethodName()
	 */
	/**
	 *在目标bean实例化</i>之前应用此BeanPostProcessor<i>。
	 *返回的bean对象可以是要代替目标bean使用的代理，
	 *有效地抑制目标bean的默认实例化。
	 *＜p＞如果此方法返回非空对象，则bean创建过程
	 *将被短路。唯一应用的进一步处理是
	 *｛@link#postProcessAfterInitialization｝从配置的
	 *｛@link BeanPostProcessor BeanPostProcessors｝。
	 *＜p＞此回调将应用于具有bean类的bean定义，
	 *以及工厂方法定义，在这种情况下，返回的bean类型
	 *将在这里传递。
	 *<p>后处理器可以实现扩展
	 *｛@link SmartInstantiationAwareBeanPostProcessor｝接口
	 *以预测他们将在这里返回的bean对象的类型。
	 *＜p＞默认实现返回｛@code null｝。
	 *@param beanClass要实例化的bean的类
	 *@param beanName bean的名称
	 *@返回要暴露的bean对象，而不是目标bean的默认实例，
	 *或｛@code null｝以继续默认实例化
	 *出现错误时@throws org.springframework.beans.BeansException
	 *@参见#postProcessAfter实例化
	 *@see org.springframework.beans.factory.support.AbstractBeanDefinition#getBeanClass（）
	 *@see org.springframework.beans.factory.support.AbstractBeanDefinition#getFactoryMethodName（）
	 */
	@Nullable
	default Object postProcessBeforeInstantiation(Class<?> beanClass, String beanName) throws BeansException {
		return null;
	}

	/**
	 * Perform operations after the bean has been instantiated, via a constructor or factory method,
	 * but before Spring property population (from explicit properties or autowiring) occurs.
	 * <p>This is the ideal callback for performing custom field injection on the given bean
	 * instance, right before Spring's autowiring kicks in.
	 * <p>The default implementation returns {@code true}.
	 * @param bean the bean instance created, with properties not having been set yet
	 * @param beanName the name of the bean
	 * @return {@code true} if properties should be set on the bean; {@code false}
	 * if property population should be skipped. Normal implementations should return {@code true}.
	 * Returning {@code false} will also prevent any subsequent InstantiationAwareBeanPostProcessor
	 * instances being invoked on this bean instance.
	 * @throws org.springframework.beans.BeansException in case of errors
	 * @see #postProcessBeforeInstantiation
	 */
	/**
	 *在bean实例化后，通过构造函数或工厂方法执行操作，
	 *但在Spring属性填充（从显式财产或自动连接）发生之前。
	 *＜p＞这是对给定bean执行自定义字段注入的理想回调
	 *例如，就在Spring的自动布线开始之前。
	 *＜p＞默认实现返回｛@code true｝。
	 *@param bean创建的bean实例，财产尚未设置
	 *@param beanName bean的名称
	 *@return{@code-true}，如果应该在bean上设置财产；｛@code false｝
	 *如果应跳过属性填充。正常实现应返回｛@code true｝。
	 *返回｛@code false｝还将阻止任何后续的InstantiationAwareBeanPostProcessor
	 *在这个bean实例上调用的实例。
	 *出现错误时@throws org.springframework.beans.BeansException
	 *@参见#postProcessBefore实例化
	 */
	default boolean postProcessAfterInstantiation(Object bean, String beanName) throws BeansException {
		return true;
	}

	/**
	 * Post-process the given property values before the factory applies them
	 * to the given bean.
	 * <p>The default implementation returns the given {@code pvs} as-is.
	 * @param pvs the property values that the factory is about to apply (never {@code null})
	 * @param bean the bean instance created, but whose properties have not yet been set
	 * @param beanName the name of the bean
	 * @return the actual property values to apply to the given bean (can be the passed-in
	 * PropertyValues instance), or {@code null} to skip property population
	 * @throws org.springframework.beans.BeansException in case of errors
	 * @since 5.1
	 */
	/**
	 *在工厂应用给定属性值之前对其进行后处理
	 *到给定的bean。
	 *＜p＞默认实现按原样返回给定的｛@code pvs｝。
	 *@param pvs工厂将要应用的属性值（从不｛@code null｝）
	 *@param bean创建了bean实例，但尚未设置其财产
	 *@param beanName bean的名称
	 *@返回要应用于给定bean的实际属性值（可以是传入的
	 *PropertyValues实例），或｛@code null｝跳过属性填充
	 *出现错误时@throws org.springframework.beans.BeansException
	 *@自5.1
	 */
	@Nullable
	default PropertyValues postProcessProperties(PropertyValues pvs, Object bean, String beanName)
			throws BeansException {

		return pvs;
	}

}
